home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 May: Tool Chest / Developer CD Series Tool Chest (Apple Computer)(May 1999).iso / Tool Chest / Development Kits / MPW etc / MPW-GM / MPW / Examples / HyperXExamples / Instructions < prev    next >
Encoding:
Text File  |  1998-12-03  |  7.6 KB  |  165 lines  |  [TEXT/MPS ]
  1. Instructions - The HyperCard XCMD Examples
  2.  
  3. Copyright Apple Computer, Inc. 1988,1992
  4. All rights reserved.
  5.  
  6.  
  7. About the Examples
  8.  
  9.     MPW 3.0 introduces a consistent interface to callback HyperCard
  10.     routines from within XCMDs and XFCNs. The HyperCard XCMD Examples
  11.     are intended to introduce the use these routines. More importantly,
  12.     they are to serve as models for good software development of XCMDs
  13.     and XFCNs using MPW 3.0. We provide examples of both an XCMD and 
  14.     an XFCN written in all three languages provided by Apple Computer,
  15.     Inc. as part of the Macintosh Programmer's Workshop: assembler, C
  16.     and Pascal.
  17.     
  18.     The files provided with this set of examples is:
  19.     
  20.         LittleDialog.a        - sample XCMD to display a dialog box in assembler.
  21.         LittleDialog.c        - sample XCMD to display a dialog box in C.
  22.         LittleDialog.p        - sample XCMD to display a dialog box in Pascal.
  23.         LittleDialog.r        - resources for assembler, C or Pascal LittleDialog.
  24.         Reduce.a                - sample XFCN removing tabs and spaces in assembler.
  25.         Reduce.c                - sample XFCN removing tabs and spaces in C.
  26.         Reduce.p                - sample XFCN removing tabs and spaces in Pascal.
  27.         Make                    - script to build and install the above XCMDs.
  28.         'HyperXExample Stack'    - minimal stack to test XCMDs and XFCNs.
  29.     
  30.     (Please note that the HyperXExample Stack requires HyperCard 2.0 or later.)
  31.  
  32.     They will rely upon the following interfaces and library:
  33.     
  34.         {AIncludes}HyperXCmd.a
  35.         {CIncludes}HyperXCmd.h
  36.         {PInterfaces}HyperXCmd.p
  37.         {Libraries}HyperXLib.o
  38.  
  39.     Note that these files are different from those provided with the original
  40.     HyperCard Toolkit released through APDA. The differances are:
  41.     
  42.         HyperXCmd.p:
  43.             HyperXCmd.p declares the functions and procedures necessary to
  44.             access the code in HyperXLib.o. THESE ROUTINE DECLARATIONS ARE
  45.             DIFFERANT FROM THOSE WITH THE SAME NAME RELEASED THROUGH APDA:
  46.             In all cases, the XCmdPtr passed by HyperCard to the XCMD must
  47.             now be an additional parameter passed on to the library routines.
  48.             Additionally, several commands were changed to match the internal
  49.             workings of HyperCard itself: All Str31 values are really Str255.
  50.             Plus the former functions, BoolToStr, ExtToStr, LongToStr, NumToStr
  51.             & NumToHex, are now all procedures that take a VAR parameter. As a
  52.             bonus, we have added the call: SendHCMessage. THE HYPERCARD TOOLKIT
  53.             FILE XCmdGlue.inc IS NO LONGER USED!
  54.  
  55.         HyperXCmd.h:
  56.             HyperXCmd.h also declares the functions necessary to access the
  57.             code in HyperXLib.o. Only in some cases are these routine declarations
  58.             differant from those with the same name released through APDA:
  59.             Parameters that were StringPtr or Str31 values are now specified
  60.             as either char * or Str255. THE HYPERCARD TOOLKIT FILE XCmdGlue.inc.c
  61.             ALSO IS NO LONGER USED!
  62.     
  63.  
  64. Building the Examples
  65.  
  66.     Provided with the HyperCard examples is an MPW Make file. In order to build
  67.     the examples, you must type "Make", followed by "AExamples", "CExamples", or
  68.     "PExamples". Alternately, you can copy one of the following lines to your
  69.     Worksheet:
  70.     
  71.         Make AExamples
  72.         Make CExamples
  73.         Make PExamples
  74.  
  75.     After entering the command, press the Enter key. Make will then produce command
  76.     lines to assemble, compile, link, and/or rez the source code and install the
  77.     finished XCMD directly in the test stack. Select these lines (an easy way to do
  78.     this is to Undo (Cmd-Z) twice in a row) and press Enter again to complete the
  79.     build process .
  80.     
  81.  
  82. Writing Your Own XCMDs
  83.  
  84.     Within a stack, each XCMD must have a resource id that differs from all other
  85.     XCMDs in that stack. The same is true for XFCNs. Choose a unique resource id
  86.     for your XCMD and add it and the name of your file to the Makefile.
  87.  
  88.     HyperCard actually accesses XCMDs by calling GetNamedResource. This requires
  89.     the name of the resource to be the same as the command. When the linker creates
  90.     the XCMD or XFCN resource, it uses the name of the code segment as its default
  91.     resource name. The Make file sets the name of the segment to be the same as
  92.     the file name by using the linker's -sg option. Thus the file name should be
  93.     the same as you want the command name to be.
  94.     
  95.     The XCMD must be a single code segment. The main procedure has the form:
  96.         PROCEDURE EntryPoint(paramPtr: XCmdPtr);
  97.     This is a Pascal style procedure, so the XCMD itself is responsible for removing
  98.     the parameter from the stack. In C, we accomplish this by defining the routine as:
  99.         pascal void EntryPoint(XCmdPtr paramPtr);
  100.     
  101.     HyperCard executes the XCMD by jumping to the beginning of it so the entry point
  102.     to the code must be the first thing. This is no problem for assembler and C,
  103.     where the main segment can simply be placed first. In Pascal, however, this may
  104.     not be sufficient. If the main procedure has nested functions, they will be
  105.     compiled before the main code. We get around this by having a dummy first
  106.     procedure with no nested routines, which then calls the real XCMD code:
  107.  
  108.         PROCEDURE RealXCMD(paramPtr: XCmdPtr);    FORWARD;
  109.  
  110.         PROCEDURE EntryPoint(paramPtr: XCmdPtr);
  111.             BEGIN
  112.                 RealXCMD(paramPtr);
  113.             END;
  114.         
  115.         PROCEDURE RealXCMD(paramPtr: XCmdPtr);
  116.             BEGIN
  117.                 ...
  118.             END;
  119.     
  120.     The initial FORWARD declaration of RealXCMD allows us to call the real XCMD
  121.     procedure from EntryPoint, but does not generate any code. The advantage of
  122.     allowing nested procedures is the ability to share variables between routines
  123.     without passing them as arguments. This is because NO GLOBAL VARIABLES are
  124.     allowed for an XCMD. Since the default storage for strings in MPW C is along
  125.     with the globals, it is necessary to use the -b option introduced with MPW
  126.     3.0 C in order to include the string data with the code resource.
  127.     
  128.     Having mentioned placement of string data within the code resource, it is
  129.     necessary to emphasize that it is recommended that strings be placed as 
  130.     resources. This allows easy adaptation of stacks with XCMDs to international
  131.     locations.
  132.  
  133.     Unfortunately, at this time,HyperCard does not have a convention for resources
  134.     belonging to XCMDs or XFCNs. Currently using a resource mover to copy the
  135.     XCMD or XFCN to another stack can leave needed resources behind. There are
  136.     two things that can be done to help prevent such errors:
  137.  
  138.         1. To indicate that a resource may belong to an XCMD, the example LittleDialog
  139.         uses resources having the same id number as the XCMD itself. This is not a
  140.         complete solution since it will not work for an XCMD which has more than one
  141.         resource of a given type. This is therefor only a suggestion until a better
  142.         means of bundling XCMDs with other resources is developed.
  143.     
  144.         2. Within the code of the XCMD, always check for the availability of of the
  145.         resource before it is to be used. Then, if the resource is missing, report it
  146.         as an error that indicates what resource is missing.
  147.  
  148.     The linker must be provided with the name of a main code segment so it can stip
  149.     unused code (mostly from the libraries we link with) from our XCMDs. Our Make
  150.     script includes the linker option -m ENTRYPOINT. The linker is case sensitive,
  151.     but Pascal symbols, C functions cast as "pascal", and the default case for
  152.     assembler symbols are not case sensitive, i.e. converted to all upper-case,
  153.     our main entry point for the linker should be in all upper-case also. XCMDs
  154.     do not require the main routine to be named EntryPoint. However, since that
  155.     was the name invented for the dummy pascal entry procedure, we have used it
  156.     as the default name in our script. It was due to this agreeing with the scipt
  157.     that all the examples here have main routines named EntryPoint.
  158.  
  159.  
  160. In Conclusion
  161.  
  162.     In keeping with HyperCard's efforts to make program development easier on
  163.     the Macintosh, we have tried to introduce a more uniform method of creating
  164.     XCMDs to expand the utility of HyperCard. Good luck and have fun!
  165.